Cream of the Crop 25

home *** CD-ROM | disk | FTP | other *** search

/ Cream of the Crop 25 / Cream of the Crop 25.iso / os2 / srefv12i.zip / initfilt.doc < prev next >

Wrap

Text File | 1997-04-19 | 104KB | 2,671 lines

Optimization hints, configuration information, and other commentaries on SRE-Filter. 5 Mar 1997. This file contains several sections discussing various aspects of SRE-Filter. 1) Optimization hints: a discussion of ways of speeding up SRE-Filter 2) Configuration information: a complete description of all the SRE-Filter intialization parameters: including the more important parameters set in INITFILT.80, and the more obscure parameters set in SREFILTR.80. 3) Remote vs. local redirection: A discussion of the various methods SRE-Filter uses to redirect files. 4) A sample site: A short example of how one might use PUBLIC_URLS to efficiently set up a site. =========================================== SECTION 1. Performance hints (a) The use of the server side include cache (SSI-Cache) is highly recommended. However, for very dynamic documents (such as documents that contain several INTERPRET and #EXEC keyphrases), it may be more efficient to suppress caching of these files (you can use the  keyphrase for just such a purpose). Upgraders note: now that the SSI-cache has been added to SRE-Filter, we NO LONGER RECOMMEND using the "send in pieces" option (as set by the DO_SEND_PIECE parameter). (b) Suppressing incorporation of server side includes (SSIs) i) If you set SSI_SHTML_ONLY='YES', and name html documents, that contain SSIs, with a .SHT or .SHTML extension: SRE-Filter will not attempt to process SSI's in .HTM or .HTML files. This can save some processing time. In fact, if you are using GoServe's caching mechanism (see c below), this can save a lot of processing time! ii) If you are willing to NOT have SSIs, then set NO_INCLUDE='YES' (this saves more processing time, and it also makes hints (a) and (b.i) totally irrelevant) (c) Turn on GoServe's cache. This will have no effect on documents containing server side includes, but can greatly speed up transfer of other documents (such as .GIF files). However, if you have imposed any access controls, SRE-Filter will suppress caching. To get around this, you can use the CACHE permission. The CACHE permission (in the ACCESS_FILE) instructs GoServe to allow caching on a request specific basis. One good use of this CACHE option is to cache .GIF files that are used as in-line images (and that of themselves contain no proprietary information or are unlikely to be requested explicitily). Note that html documents that have been processed for server side includes will never be cached, regardless of the use of this CACHE permission. Use CACHE with care, since cached files are sent to all requesters! (d) If you never check "access" info, or virtual directories, set the access_file and virtual_file to " " (or see note e). Note that the access file can contain (on a SEL-specific basis): i> access control information, ii> ssi, ssp, delete, and put permissions, iii> NO_VIRTUAL, NO_ALIAS, and NO_POSTFILTER permissions iv> the "always cache flag", v> and realm information. Thus, with access_file="": * these permissions (et al) will equal to " " * CAUTION: if allow_access="NO" and ACCESS_FILE=' ', then site access is given only to SUPERUSERS (e) Use the NO_VIRTUAL, NO_ALIAS, and NO_POSTFILTER "permissions" in the ACCESS_FILE to suppress unnecessary processing. (f) If you have a choice, the ACCESS_FILE method is preferable to the the HTACCESS access control method: HTACCESS it is not implemented with quite the same attention to efficiency. Or, use the NO_HTACCESS permission (in your ACCESS_FILE) whenever possible. (g) If you have some documents that are supposed to be available to everyone, and these documents do not have server side includes, set up PUBLIC_URLS entries for them (since public_urls are cached if possible) (h) If ... you are serving only 1 host, you have many selectors that you can specify with PUBLIC_URLS, and these "selectors" are to be interpreted "literally" -- with no internal redirection, auto-header creation, and no server side includes -- then ... you can greatly improve throughput by using the SREFQUIK.80 filter instead of SREFILTR.80. SREFQUIK.80 is small filter that processes these "literal public_urls" on a single host server (it also recognizes "cached" returns). When a "literal public_url" is requested, SREFQUIK does all the work, saving a great deal of overhead. That is, the main filter (SREFILTER) is never called! On the other hand, if the request selector does not match a "literal public_url", the standard filter is called, with no loss of capability. Notes and Cautions: * Caution #1: Since SREFQUIK adds overhead to requests that are NOT to "literal public_urls", if you specify few "literal public_urls" the net effect may be detrimental. So, when using SREFQUIK, it is important to specify as many "literal public_urls" as possible. * Caution #2: If you modify SREFILTR.80 and are using SREFQUIK as your filter, be aware that the modifications to SREFILTR.80 will take effect AFTER you stop, then restart, GoServe. * Caution #3: If you have specified multiple hosts (using the HOSTS. variables) , SREFQUIK should NOT be used. * Caution #4: If you use SREFQUIK, "cached" responses (requests that GoServe was able to satisfy from it's cache) will not be checked for the NO_POSTFILTER access permission (SREFQUIK offers a work-around for this problem). * For a description of "literal public_urls", see the discussion of the PUBLIC_URLS variables, and see Section 4 of this document * For further details on the SREFQUIK "mini-filter", see SREFQUIK.DOC. (i) Turn on the RECORD_ALL_FILE cache. This is useful ONLY if you are recording all requests (i.e.; RECORD_OPTION='YES'). Turning on the cache will cause the RECORD_ALL_FILE to be cached in memory, with disk-writes every 5 minutes. See the description of RECORD_CACHE_LINES for details. (j) If you don't need extensive auditing, set WRITE_LOGS=0 (k) It you don't need "dynamic privileges", set CHECK_ADD_PRIVS='NO'. (l) As an illustrative example; an apppendix at the bottom of this document contains a discussion of how to use SREFQUIK, PUBLIC_URLS, etc. to efficiently setup a site with three levels of security. ============================= Section 2. Parameter descriptions The following parameters are in alphabetical order (by name of parameter). Many of them can be changed by using SRE-Filter's configurator, especially the "intermediate mode" configurator. However, to changes several of these parameters, you must "hand-edit" the INITFILT.80 file. In general, the "hand-edit only" parameters are more obsure, and may never need to be changed. "Power users" may wish to see section 2a (below) for a discussion of variables contained in SREFILTR.80 -- these are "doubly obscure" variables! Miscellaneous Notes: * The terms "variable" and "parameter" are used interchangeably. * In almost all cases the variables (aka parameters) are set to equal strings, so if you are "hand editing" INITFILT.80, remember to put single quotes (') around the stuff on the rhs of the = sign. * When this document mentions "SEL-specific", it really means "selector specific", where the selector is the slightly modified middle portion of the request string sent by the client to the server. For example, if the client requests a URL of: http://your.server/animals/bear.jpg her brower will issue a request string of: GET /animals/bear.jpg http/1.0 and the selector would be animals/bear.jpg Notes on Host-specific parameters: * Almost all of the parameters (that are set in INITFILT.80) may be "host specific". The several that aren't are: INTERPRET_TYPES, DISPLAY_ENV, and HOSTS. * Parameters set in SREFILTR.80 (described in section 2a) can NOT be host specific (they apply to all hosts). * To specify a host-specific parameter, you append the "host nickname" to the parameter name (see the HOSTS. variable for a discussion of host nicknames). For example, to set the CHECKLOG variable for the ZOO host, CHECKLOG.ZOO='NO' and for all other hosts: CHECKLOG='ALWAYS' where this non host-specific value (CHECKLOG='ALWAYS') is the "generic" value, and will be used for hosts other then the "ZOO" host. * When a request to a host is recieved, SRE-Filter will attempt to find the appropriate host-specific parameters. If a given parameter does not have a host-specific value, the "generic" (the value of the non host-specific parameter) is almost always used instead. The exceptions are: UNALLOWEDIPS., INHOUSEIPS., PUBLIC_URLS. * For security reasons, for these three (sets of) parameters the generic (non host-specific) values are NOT used as a default. The astute reader may notice that the OWNERS variable is not on this list of "exceptions". In other words, the "generic" OWNER has SUPERUSER privileges for ALL hosts. Note on "hand edited" parameters: * Currently, the "hand-edited" parameters (that can NOT be set with the intermediate mode configurator) are: ACCEPT_RANGE ADD_USER_NAME ADD_RESOURCE_NAME ADD_PRIVS_PREFIX CHECK_ALIAS DELIM_1.n DELIM_2.n DISPLAY_ENV DO_SEND_PIECE HTACCESS_FILE INTERPRET_TYPES MAX_POINTDIST NO_INCLUDE NO_PROCESSING NO_INTERPRET_CODE PREFILTER_NAME POSTFILTER_NAME USE_STDOUT VERBOSE ************ ACCEPT_RANGE: Return only specified range of the request file You can instruct SRE-Filter to respond to a "range:" request header. If such a request header is present, SRE-Filter will extract the "byte range" information, and return only this portion of the request file. Primary use: Adobe Acrobat can use this to request a given page in a long .pdf file. If accept_range=NO, this processing will not occur -- the entire file will always be returned. If accept_range=YES, this processing will occur. Of course, if there is no range: header, then the entire file is returned. Accept range is only used when a non-html file is requested. Example: accept_range='YES' For more information on "byte range retrieval", see the document: draft-ieft-http-range-retrieval-00.txt at ds.internic.net. Note on GoServe and Multi-part sends: GoServe is a bit flaky with multi-part sends (byte retrieval being a form of multi-part send). We suggest obtaining GoServe ver 2.50 from: http://www2.hursley.ibm.com/goserve/ (ACCEPT_RANGE can be host specific) *********** ACCESS_FAIL_FILE If a SEL-specific access is not granted to the client, you can send the ACCESS_FAIL_FILE as a response. ACCESS_FAIL_FILE should be one of the following values: -1 : Do NOT send a message or ask for authorization. This is useful when combined with "dynamic privileges" 0 : Do NOT use an access_fail_file -- just ask for authorization 1 : If a "SEL-specific" access file exists (as set in ALL_FILE.CTL), use it. Otherwise, ask for authorization filename.ext : The fully qualified file name to be used when access is denied. Note that this may be overridden by a "SEL-specific" access-fail file. As with the LOGON_FAIL_FILE, when the ACCESS_FAIL_FILE is an HTML document, server side includes are NOT attempted. However, for HTML documents a few special substitutions will occur:  phrases are substituted with the request selector.  phrases are substituted with the servername.  phrases are substituted with the WEBMASTER variable.  phrases are substituted with a short description of the reason for failure  phrases are substituted with a "forced" URL: which points back to this resource, and forces an "ask authorization" if access is denied. It is HIGHLY recommended that a #LINK be included. Without such an entry, the client will be unable to enter a new username/password, should his first entry be misspelled (or if he had previously used a different username/password for a different resource on the same server). PROVISO: In some cases (such as when dynamic privileges are used to control access to .GIF files), you may want to use an ACCESS_FAIL_FILE that does not contain a #LINK. Or, set ACCESS_FAIL_FILE=-1 (for a very terse "Access denied" response). Notes: * When set to ACCESS_FAIL_FILE=0, the client will be re-sent an authorization request. * If ACCESS_FAIL_FILE=0, SEL-specific failure files are NOT used, even if one is available. * The #LINK entry uses a special form of SRE-Filter request selector. The effect is to force SRE-Filter to request authorization should the current username/password be incorrect; thereby avoiding an annoying recursive trap. (ACCESS_FAIL_FILE can be host-specific) *********** ADD_USER_NAME: Controls whether a clients "logon name" should be added to the list of client privileges. YES: Add logon name to client privilege list NO: Do not add logon name to client privilege list. This can be a useful means of personallizing a client's privilege list (of course, you could always enter his name in the privilege list explicitly when setting up his username/password entry). Example: ADD_USER_NAME='YES' Usage Example: if a username of ACIDER exists, with a client privileges of HARD SOFT, then if ADD_USER_NAME='YES', an ACIDER client privilege is added (yielding a client privilege list of ACIDER HARD SOFT). Notes: * For INHOUSEIPS. entries, the "clientname" (the full, dotted, IP name) is used as the "logon name". * If you set ADD_USER_NAME=1, you should be careful that the usernames you assign (in the USERS.IN file) do not conflict with the words used for privileges. In particular, don't casually give someone a username of SUPERUSER or INHOUSE. *********** ADD_RESOURCE_NAME: Controls whether the "action" portion of the request selector be included as a resource privilege. YES: Add the action to the resource privilege list NO: Do not add. Similar to the ADD_USER_NAME, this can be a useful shortcut in environments where highly specific access controls are required. CAUTION: When ADD_RESOURCE_NAME='YES', unmatched requests will require clients to have a privilege matching the "requested resource". Example: ADD_RESOURCE_NAME='YES' Notes: * The "action" portion of a request selector is everything before the first ? character (if no ? is found, the entire request selector is used). * If ALLOW_ACCESS='YES', ADD_RESOURCE_NAME has no effect. ************ ADD_PRIVS_PREFIX: Modifies the prefix used to distinguish "dynamic" client privileges. As a security measure, when SRE-Filter adds "dynamic" privileges, it will append the ADD_PRIVS_PREFIX. For example, if ADD_PRIVS_PREVIX='!', and a  keyphrase appears in a requested document, the client will be granted a !SATURN client-privilege (in this example, for 30 minutes). The rationale is to prevent unscrupulous individuals, who may have been granted a limited ability to post documents to "user" sub-directories, from subverting access control with keyphrases of the form:  If such problems are not likely to occur, you may want to set ADD_PRIVS_PREFIX=' ' Example: ADD_PRIVS_PREFIX='!' (ADD_PRIVS_PREVIX may be host specific) ************ ALLOW_ACCESS : Control access to server resources. You can check "access privileges" for server resources (files, programs, etc.) by setting the ALLOW_ACCESS variable. YES : no access control INHOUSE : don't check in-house and superusers. NO : don't check superusers. Note that checking involves examination of privilege information on a per-request-selector basis (using the ACCESS_FILE file). The ACCESS_FILE is also used for: 1) Controlling server side include privileges and server side processing, on a SEL-specific basis 2) Allowing caching of files that would normally not be cached (If CHECKLOG<>"YES" or ALLOW_ACCES<>"YES", then caching is suppressed). 3) Setting the default "realm" of the resource (see the THE_REALM variable) 4) Permitting PUT and DELETE methods to operate 5) Suppressing aliasing, virtual directory lookup, and "post-filtering" If you do not ever want SRE-Filter to check the access file, just set access_file=" ". BUT if you do, the above features will not be available! Notes: * The default name of the ACCESS_FILE is ALL_FILE.CTL (in the DATA/ directory of GoServe's "working" directory). * WARNING: If you set allow_access="NO", and access_file=" ", then only SUPERUSERS will have access to your site! (ALLOW_ACCESS can be host specific) ******** AUTO_HEADER. Automatic generation of response headers. AUTO_HEADER is used to automatically generate response headers, based on LINK and META HTTP-EQUIV elements in the <HEAD> section of HTML documents. 3 values are supported: NO : Do not generate these headers HEAD : Generate headers for HEAD requests only ALWAYS : Generate headers for HEAD and GET requests. Note that this is only relevant for HTML files. Also, when AUTO_HEADER occurs, the html file is parsed for header information before server side includes are attempted -- that is, any server side include in the <HEAD> of a document will NOT appear in the response headers (but they will appear in the body of the response). IN OTHER WORDS -- Server Side Includes SHOULD NOT BE USED IN THE <HEAD> portion of an HTML document (unless you do not intend to automatically generate response headers) Example: AUTO_HEADER="HEAD" Technical note: HTTP purists would disapprove of the use of the "HEAD" value; since HEAD method requests are "supposed to" return exactly the same response headers as GET method requests. (AUTO_HEADER can be host specific) ********* AUTO_NAME : Resolving requests for directories. AUTO_NAME is used to deal with non-specific requests that are NOT to the root (the /) directory. AUTO_NAME should contain a space delimited list of potential "directory specific default names". Several special names are supported: *.HTM or *.HTML : means "use the "directory" name, with .HTM or .HTML appended !CREATE : Create a list of links, one for each file in the directory. !CREATE* : Same as !CREATE, but include links to subdirectories Example: AUTO_NAME=" *.HTM INDEX.HTM PAGE.HTM DESCRIBE.HTM !CREATE " If a request for xxx/yyy/ (with optional ?abc after the final /) is recieved, then first, yyy.htm is looked for (in datadir/xxx/yyy) second, INDEX.HTM (in datadir/xxx/yyy). Then PAGE.HTM, and then, DESCRIBE.HTM are tried. If all these fail, !CREATE signals "just display a list of the files in this directory". Note that if !CREATE were not included in this list, and none of the requested files exist, a not_found message is returned. Similarly, if !CREATE fails (if there is no such directory), the not_found message is returned (see the description of NOT_FOUND_URL for details). Notes: * AUTO_NAME is NOT used when request is to the root (to /) -- DEFAULT is used! * See NOEXT_TYPE for a discussion of how to deal with requests that have neither an extension or a trailing / (i.e.; xxx/yyy). * You can put a "pathed" name (using /, relative to the data directory) This is one means of handling bad requests (but only if the request ends in a /) -- just put the home page document in the auto_name list, i.e.; auto_name=" * INDEX.HTM /HOMEPAGE.HTM " * It is recommended that a !CREATE be placed at the end of the AUTO_NAME list (since !CREATE is "always a match", assuming the request points to a valid directory) Example: AUTO_NAME=" * INDEX.HTM " (AUTO_NAME can be host specific) CAUTION: When using AUTO_NAME (and other types of local redirection) URL resolution by the client's browser may have unexpected consequences. See the discussion of "local vs remote redirection" at the bottom of this document for details! ************** CHECK_ADD_PRIVS: Check for "dynamic privileges" CHECK_ADD_PRIVS is used to instruct SRE-Filter to check for "additional, dynamic privileges", and if they exist, add them to the client's "privilege" list. CHECK_ADD_PRIVS can take two values; YES : Check for additional, dynamic privileges NO: Do NOT check for additional, dynamic Example: CHECK_ADD_PRIVS='NO' Note: * When CHECK_ADD_PRIVS='YES', an _ADDPRIV.DOC file is created in the TEMPDATA_DIR directory (typically, \GOSERVE\TEMP). * See ADDPRIVS.DOC for a detailed discussion of "additional, dynamic" privileges. (CHECK_ADD_PRIVS can be host specific) *************** CHECK_ALIAS: Controls whether alias checking occurs. SREFILTR can check all requests to see if they are aliases for some other action. Uses of aliases include: * implementation of searchable indices * "local" redirection -- useful as a means of assigning proper document names to abbreviations (say, to convert an request of OVERVU into OVERVIEW.HTM) * "remote" document redirection -- typically to a different ip addreess * transferring non-data directory files Setting CHECK_ALIAS to -- NO suppresses this alias lookup YES causes this lookup to be done for all requests Example: CHECK_alias="YES" (CHECK_ALIAS can be host specific) ************ CHECKLOG: When and how to check for "logon rights". "Logon rights" refer to basic site access rights. These may be used with, or without, SEL-specific access privileges (see ALLOW_ACCESS) CHECKLOG can take four values: 1) NO -- never check (basic access granted to all clients) 2) YES -- check when default document (either explicitily, or if a / is requested). Thus, a request for a specific document does not require logon rights. 3) ALWAYS -- check on every request. 4) INHOUSE -- Only let IN-HOUSE users in. IN-HOUSE users are determined by occurence of a INHOUSE in the client's 'privilege list', or if the client has an IP address listed in the INHOUSEIPS.n variables. Note: if ALWAYS or INHOUSE is selected, then GOSERVE will NOT cache GET requests (the discussion of the ALLOW_ACCESS variable describes an exception to this through the use of the CACHE permission) Example: checklog='NO' (CHECKLOG can be host specific) ********** DEFAULT -- The "default" (home) page. Use this when a default request (say, http://www.joe.com/ ) occurs. Note: it is traditional, but by no means required, to use INDEX.HTM as your default You can also use DEFAULT to redirect a request (using a 301 redirection), say, for an IP Alias that has moved. To do this, just enter the full URL -- be SURE to include the leading http:// Examples: default='index.htm' default.zoo='ourzoo.htm' default.circus='http://silly.places.net/bigtop.htm' Note that default.zoo defines the DEFAULT file for requests to the ZOO host only. Also note that default.circus is redirected. (DEFAULT can be host specific) CAUTION: When using DEFAULT (and other types of local redirection) URL resolution by the client's browser may have unexpected consequences. See the discussion of "local vs remote redirection" at the bottom of this document for details! ********** DIR_EXCLUSION: A list of files and subdirectories that the !DIR directory lister should exclude. SRE-Filter's !dir function can be instructed to suppress displaying certain files and subdirectories. To do this, one uses the DIR_EXCLUSION parameter. DIR_EXCLUSION should contain a space delimited list of files and subdirectories". Example: dir_exclusion='Htaccess. /private describe.txt *.CNT ' Note that a / must preceed subdirectories (otherwise, the entry is interpreted as a file name). Notes: * The !dir function is used by the !CREATE option of AUTO_NAME. * Subdirectories are assumed to be relative to the "requested directory", and should only be one name deep. That is, an entry of /personal/family would be ignored. * The wildcard character (*) can be used in file and directory names. * For a further discussion of the !dir function, see DIR.DOC. (DIR_EXCLUSION can be host specific) ********** DIR_OPTIONS: Set the display options of the !dir function. To control the display option of SRE-Filter's !dir function, you should modify the DIR_OPTIONS parameter. DIR_OPTIONS should contain a space delimited list of parameters. The allowed options are: AUTO_DESCRIBE DESCRIBE DESC_LEN DATEFMT MULTI_SEND NOSIZE NOTIME NODATE NOICON NOSORT NODIR NO_RECURSE_DIR SIZEFMT SHOWPARENT TABLE TABLE_BORDER TIMEFMT For a description of what these options do, see DIR.DOC. Example: DIR_OPTIONS='notime auto_describe describe datefmt=u ' Notes: * The !dir function is used by the !CREATE option of AUTO_NAME. (DIR_OPTIONS can be host specific) ********** DISPLAY_ENV -- write "SRE-Filter" environment variables to PMPRINTF Use this as a debugging tool to display the values of the SRE-Filter enviroment variables in the PMPRINTF window. DISPLAY_ENV = 1 : The SRE-Filter environment variables (basically, transforms of everything in INITFILT.80 and REPSTRGS.IN) are written to the "PMPRINTF" window. This will occur whenever the environment variables are refreshed (say, when you change INITFILT.80). otherwise : Do not write environment variables. Example DISPLAY_ENV=0 (DISPLAY_ENV is NOT host specific) ************* DELIMITERS for KEYPHRASES SREFILTR does "server side" includes by looking for keyphrases in your HTML documents. A keyphrase is defined as: delim1 keyword keyvalue delim2. Delim1 and Delim2 are strings (possibly 1 character) that signal the location of the keyphrase. These delimiters should be odd, yet easy to remember (and not likely to occur in your text). ALTHOUGH WE DO NOT RECOMMEND IT, you can enter several sets of delimiters. One useful set is the HTML comment delimiters '' . If you use these, the raw document will not look too wierd should it be accidentally sent to the client "as is"). For each set of delimiters, You MUST specify both the beginning (DELIM_1) and end (DELIM_2) delimiter. Examples: delim_1.1="" delim_1.2="{" delim_2.2="}" delim_1.3=0 delim_2.3=0 or, if just the ZOO host should recognize a second set of delimiters delim_1.1="" delim_1.2=0 delim_2.2=0 delim_1.1.zoo="" delim_1.2.zoo='{' delim_2.2.zoo='}' delim_1.3.zoo=0 delim_2.3.zoo=0 Note: The most important reasons for NOT using several sets of delimiters: * SSI-Caching will be turned OFF (regardless of value of SSI_CACHE_ON) * SSI processing will be slower * DO_SEND_PIECE will be turned OFF But if you are willing to accept these performance disadvantages, then the use of several delimiters should cause NO problems. (DELIMS can be host specific) ************************* DNS_CHECK: Force DNS check before access As a security measure, you might want to look up the IP name of the client (using the client's IP address and his DNS). If no name can be found, logon is not allowed. NO: do not check DNS for an IP name YES: Force lookup of IP name before allowing access Although this will provide some security agains "fake" IP addresses, it will also slow down response time. Furthermore, many legitimate clients may not have "names" (say, if they are using pooled IP addresses). DNS_CHECK='NO' (DNS_CHECK can be host specific) ******** DO_SEND_PIECE: Allow SRE-Filter to send "pieces" of a document as they become available. NOTE: We no longer recommend enabling the DO_SEND_PIECE parameter -- it conflicts with the SSI Cache (that is, we recommend DO_SEND_PIECE=0). To speed up percieved throughput for large documents that contain server side includes, transferal of earlier portions of the document "as they become" available is recommended. DO_SEND_PIECE controls this feature, with values: NO : Do NOT send "pieces of the document" as they become available (send the entire document when it's ready) YES: DO send these pieces. DO_SEND_PIECE is ignored if there is more then one set of delimiters, or if FIX_EXPIRE is greater then 0. If either of these hold, "pieces" will NOT be sent (that is, DO_SEND_PIECE is set to NO). Example: DO_SEND_PIECE='NO' WARNING: If you want to "set header elements" (such as cookies) by using server side includes (i.e.; by using INTERPRET keyphrases), then you MUST set DO_SEND_PIECE='NO' (DO_SEND_PIECE can be host specific) ******** DO_HTACCESS: Controls whether the HTACCESS method is used. To provide compatability with HTTPD style servers (such as Don Meyer's GOHTTP), SRE-Filter supports the HTACCESS method of access control (see the description of HTACCESS_FILE in INITIFLT.DOC for details). DO_HTACCESS can take two values YES: Enable support of the HTACCESS access control method NO: Do NOT support HTACCESS. Example: DO_HTACCESS='YES' When DO_HTACCESS='YES', SRE-Filter will check for an HTACCESS file in the directory (and parent directories) of the requested file. Note that this control is by "file name", rather then by request selector. Details on HTACCESS files are in the description of the HTACCESS_FILE variable. Details concerning the use of the HTACCESS method can be found at: http://w3.ag.uiuc.edu/DLM/GoHTTP/htaccess.html (DO_HTACCESS can be host specific). ********* FIX_EXPIRE: For fixing the GoServe automatic response header. For certain responses; when FIX_EXPIRE > 0 , instead of returning the default GoServe response headers, SRE-Filter will generate it's own. In particular, it will add FIX_EXPIRE "fractions of a day" to the current date/time, and use it as the File-Expires date. FIX_EXPIRE is used whenever a server-side include containing HTML document is being returned. It is also use by several SRE-Filter add-ons (such as by GETAFILE and DOSEARCH), and by CGI-BIN programs. To use it in a custom REXX program, see the description of SREF_FIX_EXPIRE in SREFPRC1.DOC (SREFPRC1.DOC is available from http://rpbcam.econ.ag.gov/srefilter/srefprc1.doc). Note that if FIX_EXPIRE=0, the default GoServe response headers will be used --plus any headers that may have been specified using the META and LINK elements in the HEAD (see AUTO_HEADER). Setting FIX_EXPIRE > 0 can be useful when relatively static (that do not depend on the current "hour") server side includes are performed. In such cases, GoServe automatically sets the expiration time to be the current moment. This can be a hassle for some clients (Netscape will reload such "expired" documents if "backed up" to). Note that a value of FIX_EXPIRE=0.1 = .1 * 24 hours = 2.4 hours. Also note that to use DO_SEND_PIECE, you must set FIX_EXPIRE=0 Example: FIX_EXPIRE=0 (FIX_EXPIRE can be host specific) Alternative method of suppressing "immediate expire": * When creating REXX server side programs, you can avoid this problem by using 'FILE TYPE ... NAME TEMPFILE ' rather then 'FILE ERASE TYPE ... NAME TEMPFILE ' -- the "expire immediately" response header is NOT added to non 'FILE ERASE' completion codes. However, you should remember to delete your TEMPFILE (use the sysfiledelete rexx procedure). ... furthermore, you may want the document to expire in a few hours, a message FIX_EXPIRE is designed to deliver. * If you are using GoServe ver 2.50, the HEADER NOTIME option can be used. SPECIAL OPTION: If you are useing GoServe 2.50, setting FIX_EXPIRE=1000 will invoke this HEADER NOTIME option. ********** HEADERS and FOOTERS: Automatically added to all HTML documents. You can specify a block of HTML code to include at the beginning and the end of the body of the document. This is done by specifying HEADERS.n (n=1...) and FOOTERS.n To suppress this, set HEADERS.1=0 and/or FOOTERS.1=0 Notes: * HEADERS.n lines are written (consecutively) just after the first <BODY> phrase in your document (see example 3 below for an exception to thisrule) * FOOTERS.n lines are written just before the last </BODY> phrase in your document. Examples: 1) Simple case: HEADERS.1=' Our docuuments are supplied as-is ' FOOTERS.1=' goodbye ' 2)To suppress headers and footers HEADERS.1=0 FOOTERS.1=0 3) The "exception": Headers.1='<BODY bgcolor="#5500aa"> <h1> This is our site! </h1> ' Whenever the HEADERS.1 lines begins with <BODY, then rather then writing the header AFTER the first <BODY ...> element, the header will replace the first <BODY ..> element. HEADERS and FOOTERS can be host specific. For example: HEADERS.1.ZOO = ' The ZOO server ' HEADERS1.1.CIRCUS = ' The Circus Site HEADERS.2.ZOO=0 HEADERS.2.CIRCUS=0 will set up a one-line header for the ZOO and for the CIRCUS "hosts". ************* HOME_DIR: The "home directory" -- used as a text replacement whenever a ~ is encountered in a request selector. A typical value of this would be "Users/". Example: HOME_DIR='USERS/' (HOME_DIR can be host specific) ADVANCED OPTION: Specifying User Subdirectories In many cases, you may wish clients to have access to particular subdirectories of your "Users" directories. For example, all "students" may have space on the server machine, some of which is used for web, and some for "personal" purposes. The goal is to give clients direct access to the "web" related directories but not to the "personal" directories. This can be achieved by including a $ in the HOME_DIR parameter. Specifically, the $ is replaced by the substring between the ~ and the first / following the ~. For example:, If the HOME_DIR=USERS/$/WWW and the request selector is /~GERALD/RESUME.HTM Then SRE-Filter will use: /USERS/GERALD/WWW/RESUME.HTM Summarizing, given a $ in the HOME_DIR. 1) SRE-Filter reads the substring (of the request selector) between ~ and the first / following the ~ (i.e.; GERALD) 2) The substring is deleted from the request selector 3) The $ in the HOME_DIR is replaced with this substring (from step 1) 4) The ~ in the modified request selector (from step 2) is replaced with the modified HOME_DIR (from step 3) NOTES: * If there is no $ in the HOME_DIR, a simple HOME_DIR for ~ replacement is done. For example, if HOME_DIR=USERS/and the request selector is /~GERALD/RESUME.HTM, the result would be /USERS/GERALD/RESUME.HTM * If a / immediately follows the ~ (in the request selector), the $ is removed from HOME_DIR (without replacement). * HOME_DIR substitution occurs BEFORE virtual file lookup and AUTO_NAME construction, but after ALIAS conversion. Thus, the ~ can point to a virtual directory (or a subdirectory of a virtual directory). * HOME_DIR for ~ substitution is also used when resolving filenames requested in server side includes. * CAUTION: Since HOME_DIR is used in a direct textual substitution, only a mild degree of syntax checking is attempted. In particular, // are converted to /. To be safe, be sure your use of ~ is internally consistent. ************** HOSTS. : Stem variable containing information on multiple hosts. The HOSTS. stem variable(s) is used to define the multiple hosts (IP addresses) your server will recognize. Each HOSTS. entry should contain the following comma-delimited information: IP_address, host_nickname, default_dir Where: IP_address is the IP address (numeric or character) of the host. You should use the full name -- do not use a "local abbreviation" (that is, don't use bill as a shorthand for bill.my.org; even though your local dns may recognize it) host_nickname is the "nickname" that you will use to refer to this host. It MUST NOT be a number -- that is, it must contain a non-numeric character. Thus, 234 is invalid, but N234 is okay. default_directory is the default data directory for this host Examples: hosts.1="dh.ag.gov , MY1 , e:\WWW1 " hosts.2=" 151.122.33.6 , H20 ,e:\www2 " hosts.3=0 If you do NOT have multiple hosts, set hosts.1=0 Note that we recommend that the last hosts. value = 0. A Caution on Using IP Aliases: IP aliases offer a convenient means of setting up multiple hosts (IP names) while only using one numeric ip address. Unfortunately, use of IP name aliases requires browsers that understand HTTP/1.1; specifically, that send the HOST: request header with each request. Although NetScape (2.0+) will do this, most older browsers will not! In these cases, SRE-Filter will use the numeric IP address (that is, it will use the "canonical name" for the IP address, rather then the desired alias). Note: When using multiple hosts, you can specify many of SRE-Filter's parameters, both here and in the various .IN, .CNT, and .CTL files, to be "host specific". For obvious reasons, HOSTS can NEVER be host specific! **************** HIT_CACHE_LEN and HIT_CACHE_DURATION: Used to limit false hits. To reduce the number of "false hits" (from clients returning to your document after a short absence, which is often caused by the use of a browser's "back" button), a current hits list can be maintained. If a request matches a request in this list (where the request selector and the client's IP address are both used), the "count of hits" will not be augmented. Specifically, the COUNTER_FILE and the RECORD_ALL_FILE will not be augmented. There are two methods of storing these current hits: in the "environment" or in a "file". 1) Environment. It's fast to access, but can not be large (OS/2 has problems with large environment strings). To specify this, set HIT_CACHE_LEN to the number of K you wish to set aside. For example: HIT_CACHE_LEN=5 (note: each request needs about 50 bytes, more if the request selector is long. Thus, this example would store approximately the 100 most recent requests) 2) File. Not as fast, but can contain an indefinite number of hits. To specify this, set: HIT_CACHE_LEN='FILE' A special file in the TEMP/ subdirectory of the GoServe "working" directory, with the name _HITCACH.80 (or .nnn if nnn is your serverport) is created and used to store recent hits. Each selector/client pair will be retained for HIT_CACHE_DURATION minutes. Note that "overflow" will NOT occur, but the _HITCACH.80 file may become large. Since "expired" entries are removed, only in rare circumstances (extremely heavy load, or when HIT_CACHE_DURATION is very large), will the file size become problemmatic. To turn of this feature, set HIT_CACHE_LEN=0 Example: HIT_CACHE_LEN=2 HIT_CACHE_DURATION=5 HIT_CACHE_LEN='FILE' HIT_CACHE_DURATION=20 Notes: * Since use of the environment to store large amounts of data can result in odd effects a limit of 50K on the size of HIT_CACHE_LEN is imposed. HIT_CACHE_DURATION is limited on the lower end to 1 (minute), with no limit on the upper end. * If you are using the FILE mode, a limit of 10,000 entries is imposed. * HIT_CACHE_LEN and HIT_CACHE_DURATION can NOT be host specific. ***************** HIT_OWNER_SUPPRESS: Used to suppress hit recording from "OWNERS" Switch to turn off and on the "suppresion of OWNER request" HIT_OWNER_SUPPRESS='YES' Do not record (in the COUNTER_FILE or RECORD_ALL_FILE) any request from an OWNERS. HIT_OWNER_SUPPRESS='NO' Requests from OWNERS are recorded. This is provided to limit the number of false hits attributable to site-maintenance operations (say, from the Webmaster monitoring her own site). Example: HIT_OWNER_SUPPRESS='YES' Note: the HIT_SUPERUSER_SUPPRESS variable (set in srefiltr.80) can be used to extend the "range" of HIT_OWNER_SUPPRESS to include SUPERUSERS. *************** HOME_NAME : The name of your organization The colloquial (not necessarily IP name) of your organization. This can be included in a document by using the REPLACE HOME_NAME keyphrase. Note it's use in NOT_FOUND_URL. home_name="DIVISION/AGENCY/DEPARTMENT/GOV" (HOME_NAME can be host specific) ******* HTACCESS_FILE : The name of the HTACCESS file. When DO_HTACCESS='YES', SRE-Filter will look in the "requested file's" directory (and it's parent's directory) for file(s) with the name given by HTACCESS_FILE. Typically, this is HTACCESS. or .HTACCESS, but you can use any name you want (but do NOT include path information). Example: HTACCESS_FILE='HTACCESS.' (HTACCESS_FILE can be host specific) Hint: The HTACCESS_FILE contains access control information, as well as URL redirection and "default index" information. To use the URL redirection, you should set up a file containing entries of the form: old_url : new_url i.e. PLANET/JUPITER.HTM : http://www.starts.edu/ss/n5.htm (note the old_url should not contain http://, and should not contain the dot address) (HTACCESS_FILE can be host specific) ******* INHOUSEIPS. : Stem variable containing IP address of "in-house" clients. You can specify any number of "in-house IP domains". Just specify the 4 elements -- you can use * for "all" (say * in 111.222.33.*) If Logon controls are desired, then clients with these IP addresses are automatically given access (they don't need to provide a username and password). In addition, you can specify extra privileges for each inhouseips. entry. Examples: inhouseips.1="151.121.64.* VIEWMESS CONTROL " inhouseips.2="JOE.USDA.GOV " inhouseips.3=0 (All clients from 151.121.64.xxx are given VIEWMESS and CONTROL privileges, in addition to the privileges contained in the INHOUSE_PRIVS variable) Notes: * If you do NOT want to identify "in-house" clients, set inhouseips.1=0 * Note that we recommend that the last inhouseips. value = 0. * INHOUSEIPS. can be host specific. In fact, non-host specific values of INHOUSEIPS will NOT be used as "default" values! For example: inhouseips.1.candy='MANAGER.STORE.COM CONTROL ' indicates that requests from MANAGER.STORE.COM to the "host" with a nickname of CANDY should be treated as an "in-House" request. Note that if no HOSTS. are specified, this entry will never be used! ******* INHOUSE. and SUPERUSERS. The following are special variables used with the INHOUSE.n and SUPERUSER.n replacement selector (see decripition of the REPLACE keyphrase). They will be displayed only for "inhouse" and "superusers", respectively. Note that INHOUSE.n variables correspond to INHOUSE.n replacement strings, and SUPERUSER.n variables correspond to SUPERUSER.n replacement strings. Examples: inhouse.1=" (Staff Version) " inhouse.2=' .. more staff stuff ' superuser.1="(Super User)" inhouse.3=0 superuser.2=0 We recommend that the last inhouse. and superuser. should equal 0. Note that inhouse. and superuser. can be host-specific; i.e.: INHOUSE.1.CANDY='Special this week: Chocolate' ************** INHOUSE_PRIVS: Privileges for IN-HOUSE clients. A space delimited list of privileges to be granted to OWNERS and IN-HOUSE clients. It is HIGHLY recommended that INHOUSE_PRIVS always contain INHOUSE as one of the privileges! Example: inhouse_privs=" INHOUSE SECRET1 " Note that INHOUSE_PRIVS can be host specific. For example: INHOUSE_PRIVS.ZOO=' INHOUSE SCHEDULES ' ******** INTERPRET_TYPES: Associate an extension with a CGI-BIN script processor SRE-Filter can use "non-REXX" processors to interpert CGI-BIN scripts. To do this, you must tell SRE-Filter which processor to associate with a file extension; where the file extension appears on the "scriptname" (that follows the CGI-BIN/ portion of the request selector). This "association" is accomplished with the INTERPRET_TYPES parameter. INTERPRET_TYPES should be a space delimited string of "type_options". Each type_option should have the form: EXT=Interpreter_invocation For example: interpret_types=' PL=PERL5 FOO=D:\FAKEIT\FOOEXEC ' The first type_option (PL=PERL5) instructs SRE-Filter to use the PERL5 program to interpret all CGI-BIN scripts with a .PL extension (this example assumes that PERL5 can be found in the OS/2 PATH). The second type_option (FOO=D:\FAKEIT\FOOEXEC) instructs SRE-Filter to use D:\FAKEIT\FOOEXEC to interpret CGI-BIN scripts with .FOO extensions. Note that a fully qualified name is used for this "FOO interpreter". Of particular interest is the use of one of the OS/2 PERL interpreters; since there is a slew of PERL scripts out there. It's not that hard to obtain a PERL interpreter -- see PERL.DOC for details on one we've had some success with. Note: by default, INTERPRET_TYPES=' PL=PERL5 ' (INTERPRET_TYPES can NOT be host specific!) ******** LOGON_FAIL_FILE If a logon failure occurs (either due to an incorrect username/password, or due to logon_limit being violated), SRE-Filter can either send a "401 Unauthorized" response; or the contents of the LOGON_FAIL_FILE. If LOGON_FAIL_FILE=0, then a "401 Unauthorized" response is sent. Otherwise, the LOGON_FAIL_FILE is sent as is; with a few substitutions:  phrases are substituted with the request selector.  phrases are substituted with the servername.  phrases are substituted with the WEBMASTER variable.  phrases are substituted with a short description of the reason for failure  phrases are substituted with a link back to this URL. Notes: * If the LOGON_FAIL_FILE is unavailable, a "401 Unauthorized" response is sent. * When using #LINK, you probably should advice the client to "wait a minute before trying again" (given that the problem might be due to logon_limit being exceeded). (LOGON_FAIL_FILE can be host specific) ***************** MAX_POINTDIST : Used with the POINT type in mappable images. Max_pointdist is used with mappable images. The "point" area is one of the 4 types of areas (circle, rectangles, polygons, points) used in selecting a URL from a mappable image. If a selected pixel does not lie in one of the first 3, or does not lie directly on top of a point; SRE-Filter determines to which (of the many possible different points that may appear in the map file) the selected pixel is closest to. However, if the distance to this closest point is greater then max_pointdist, then the Default URL is used. Thus, this limits the region of space "potentially assigned" to each point. Of course, setting max_pointdist to be very high (say, 100000), will effectively cancel this limit. Example: max_pointdist=50 (MAX_POINTDIST can be host specific) ************* NO_PROCESSING: Suppress server side processing Switch to dictate whether or not to allow server side processing. YES - Do NOT do allow server side processing If YES, then requests for server side processing will cause a 401 Unauthorized message to be returned to the client. NO - Allow server side processing. Note: A NO_SSP permission (in the access_file), overrides a NO_PROCESSING='NO'. Example: no_processing="NO" (NO_PROCESSING can be host specific) ************ NO_INTERPRET_CODE: Suppress execution of "in-document" executables. This is similar to NO_PROCESSING, but not as stringent -- it only applies to the SELECT and INTERPRET CODE "server side include" keyphrases. YES- Ignore SELECT and INTERPRET CODE server side include keyphrases. NO - Process SELECT and INTERPRET CODE server side include keyphrases. Note that NO_PROCESSING (and NO_SSP) have precedence -- if NO_PROCESSING is on, the value of NO_INTERPRET_CODE is irrelevant. Notes: * A NO_CODE permission (in the access_file) overrides a NO_INTERPRET_CODE='NO' * CGI-BIN scripts, INTERPRET FILE, and other "executed files" WILL be processed if NO_INTERPRET_CODE='YES' (assuming NO_PROCESSING, etc. is not binding). Hence:If NO_INTERPRET_CODE='YES', you can still use an equivalent INTERPRET FILE keyphrase. * The idea is that users of your site will not be able to cause trouble by including ill-mannered code into their HTML documents. In other words: i) If site administrators do not want to review HTML documents posted on their site (say, by students) ii) Site adminstrators will review CGI-BIN scripts, etc. that these "students" wish to place on the server. iii) Site administrators DO want to grant server side processing and server side include privileges to clients. Then, a reasonable level of security, without too harshly limiting flexibility can be achieved by setting NO_INTERPRET_CODE (or by judicious use of the NO_CODE permission). Example: no_interpret_code='NO' (NO_INTERPRET_CODE can be host specific) ************ NO_INCLUDE: Suppress server side includes. Switch to dictate whether or not to process server side includes (SSIs). YES : Do NOT do dynamic page processing. Files sent as is (if SSI keyphrases occur, they will be sent "as is" NO : Process server side includes. If you NEVER include SSI keyphrases, and you want to speed up processing a bit, set NO_INCLUDE="YES" Note: A NO_SSI permission (in the access_file), overrides NO_INCLUDE=NO. Example: no_include="NO" (NO_INCLUDE can be host specific) ********** NOEXT_TYPE: Determine how to handle "no extension" request selectors. NOEXT_TYPE is used to instruct SRE-Filter what to do with requests that have no extension, do not end in a /, and do not have ? in them. There are several allowed values of NOEXT_TYPE: DIR : Interpret as a directory; a / is appended to the end, and AUTO_NAME is then used. REDIR : Similar to DIR (a / is appended). However, rather then immediately using AUTO_NAME; the client is "redirected" back to this new (/ appended) URL (at which time the AUTO_NAME feature kicks in). This solves potential "resolution of local URL" problems, at the cost of slower overall response times. Note that REDIR is the default value. HTM or HTML : Interpret as an HTML file (a .HTM or .HTML is appended to the end, respectively) NONE : Use as is other_string: Append other_string. For example, if NOEXT_TYPE='.GIF', then .GIF will be appended to the end). Example: NOEXT_TYPE="DIR" (NOEXT_TYPE can be host specific) CAUTION: When using NOEXT_TYPE (and other types of local redirection) URL resolution by the client's browser may have unexpected consequences. See the discussion of "local vs remote redirection" at the bottom of this document for details! *************** NOT_FOUND_URL : A message if the requested resource is not found. This string is sent along with a generic "not found url" response. Note that it should be a valid HTML string. Set it to " " if you want no such message sent. Example: not_found_url='<a href="/"> Visit the HOME_NAME page? </a> ' Note that the HOME_NAME substring will be replaced with the current value of the HOME_NAME variable. !!! Special option !!! If you want to return a custom document, perhaps one that lists several choices, you should use a special form of NOT_FOUND_URL. Specifically: NOT_FOUND_URL= 'FILE=fully_qualified_file_name' For example: NOT_FOUND_URL= 'FILE=d:\www\notfound.htm' If you are very ambitious, you can also append a custom "reponse code". For example: NOT_FOUND_URL= 'FILE=d:\www\notfound.htm, 200 Ok with error ' (note the comma follwing the file name) The returned document will NOT have server side includes -- it is sent "as is". There are a few special exception to this rule (for HTML documents): i) all occurences of  will be replaced with the request selector. ii) all occurences of  will be replaced with the server's IP address. More notes on the FILE= variant of NOT_FOUND_URL: * You can specify any type of document (i.e.; an HTML file, a GIF file, or a plain/text file). * An fully qualified file is expected: no attempt is made to map a relative file name to the data directory. * The file can be anywhere (it need not be in the data directory, or in virtual directories). NOT_FOUND_URL can be host specific (and HOME_NAME can also be host specific). ********* OPTION_HIT_LINE : Used to write OPTION info instead of counts OPTION_HIT_LINE is used to write out "# hits drawn from an OPTION passed to me" -- that is, it used with the REPLACE OPTION_HITS keyphrase Example: OPTION_Hit_line=":: still access # " Note: OPTION_HIT_LINE is somewhat obsolete -- it's major purpose is now better accomplished by using the HIT_CACHE_LEN parameter (OPTION_HIT_LINE can be host specific) ************************* OWNERS: Assigned SUPERUSER privileges Owners are always given SUPERUSER privileges. You can specify any number of owners, just seperate each of them with a space. Note that wildcards are NOT allowed. Furthermore, you must specify an IP address (not an IP name). If there are no owners, set owners=0. Example: owners = " 151.121.65.163 " (OWNERS can be host specific). ************ PRE_FILTER: Call user written pre-filters. PRE_FILTER is used to control whether a set of user written "pre-filter" is called before SRE-Filter is given control. It can take 3 values: NO: Do not call a pre-filter. YES: Call a pre-filter after checking logon privileges (if the client does not have logon rights, the pre-filter will not be called) FIRST: Call a pre-filter as the first action (before checking logon rights) Note: if the selector matches a public_url, then: > If PRE_FILTER=FIRST, then the pre filter will be called > Otherwise, it will NOT be called (that is, PRE_FILTER="YES" is treated as a NO.) Example: PRE_FILTER="FIRST" (PRE_FILTER can be host specific) ************ PREFILTER_NAME: Name(s) of procedure(s) to call as pre-filter(s). This should point to a list of external procedures (or just to a single external procedure). Each of them will be called in turn (or until one of them responds to the client). Note that these "PREFILTER" files should be in the GoServe working directory. Examples: PREFILTER_NAME='PREFILTR' PREFILTER_NAME='PREFILT1.CMD PREFILT9.CMD ' In the first example, note that a .80 (or .nnn if using port nnn) is added to PREFILTR. (PREFILTER_NAME can be host specific) ************ POST_FILTER: Call user written post-filters. POST_FILTER is used to control whether one or more user written "post-filters " are called before SRE-Filter is given control. It can take 2 values: NO: Do not call a post-filter. YES: Call a pre-filter after sending response to client. (POST_FILTER can be host specific) ************ POSTFILTER_NAME: A series of procedures to call as post filters. POSTFILTER_NAME should contain a list (or just one) procedures that will be called as "post filters". As with other external procedures, the procedures should correspond to files with names like POSTF1.80 (they should be in the GoServe working directory). If the POSTFILTER_NAME variable is missing, a value of POSTFILT will be used. Examples: POSTFILTER_NAME='POSTRCRD.80' POSTFILTER_NAME='POST1.CMD POSTMAIL ' In the second example, first POST1.CMD will be called, and then POSTMAIL -- note that a .80 (or .nnn if using port nnn) is added to a name when there is no extension (and no final period). Notes: * Post-filters are called AFTER the client has recieved a response. Therefore, post-filters can NOT be used to modify the response. * Certain GoServe functions are NOT available to post-filter procedures (see the description of the SAVE_STATE parameter for details). * POSTFILTER_NAME can be host specific **************** PUBLIC_URLS. A stem variable containing a list of publicly accessible server resources. The basic idea is that before logon or access_controls are checked, SRE-Filter sees if the request selector matches one of the PUBLIC_URLS. If so, no logon, etc. checking is attempted. In a sense, the PUBLIC_URLS are purposely placed outside of the 'protection' of SRE-Filter's various access controls. The basic structure of a PUBLC_URLS entry is: candidate_sel anoption filename where: candidate_sel is compared against the request selector anoption can be: LITERAL LITERAL_NORECORD or NORECORD filename is a file name (with possible * "wildcard character") (anoption and filename are both optional) When the candidate_sel matches the request selector (and the * wildcard character may be included in the candidate_sel), SRE-Filter will treat the request as "a request for a Public Resource". Specifically, when anoption and filename are not specified, this means: * logon checking does NOT occur * the ACCESS_file is NOT examined * local redirections (such as home_name substitution, alias lookup and virtual directory lookup WILL occur). * server side includes may be attempted on HTML documents The anoption and filename option are included to provide further flexibility. * If anoption=NORECORD or LITERAL_NORECORD, SRE-Filter will not record the request, or perform any other "post filter" action (for example, it will not record this request in the common-log audit file). This use of NORECORD and LITERAL_NORECORD can help reduce server load. * For "literal" PUBLIC_URLS, access permissons are not looked-up. Thus, if you want to suppress post-filtering you MUST use the LITERAL_NORECORD variant (see SREFQUIK.DOC for an exception to this). * If filename is specified (after a LITERAL or a LITERAL_NORECORD), then filename is used "as is" (the data directory is not used). Actually, if filename contains a * wildcard, the usual "wildcard substitution" is attempted. The use of the filename argument allows a limited form of "aliasing" and "non-data directory file transfer" (remember: the LITERAL and LITERAL_NORECORD options suppress both virtual directory lookup and alias checking). Examples: PUBLIC_URLS.1='INDEX.HTM' PUBLIC_URLS.2='MAPS/* ' PUBLIC_URLS.3='STORE/AD1.HTM LITERAL ' PUBLIC_URLS.4='STORE/*.GIF NORECORD ' PUBLIC_URLS.5='PICTURE/HELLO.GIF LITERAL_NORECORD D:\PICTS\HELLO.GIF' PUBLIC_URLS.6='FAMILY/* LITERAL_NORECORD D:\PERSONAL\*' PUBLIC_URLS.7=0 The second gives access to everything in the MAPS/ directory (which might include imagemaps) The third specifies that STORE/AD1.HTM is to be transfered "as is", where STORE/ is a subdirectory of the data directory. The fourth specifies that all .GIF files in STORE/ be transfered, with no recording of these transfers. The fifth specifies that PICTURE/HELLO.GIF cause transfer of d:\picts\hello.gif "as is"; with no "recording" or "post-filtering" done. The sixth specifies that all requests beginning with FAMILY/ be directly mapped to D:\PERSONAL\, and transfered "as is", without recording the request. For example, a request for FAMILY/JUNE.JPG would result in D:\PERSONAL\JUNE.JPG being transferred. The seventh, PUBLIC_URLS.7=0, is not required, but is recommended to avoid possible problems should you change INITFILT.80 "on the fly" Notes: * To reiterate, the request selector (sent by the client to your server) is examined for matches to one of the PUBLIC_URLS. If multiple wildcard matches (and no exact match) occur, the "best" match is used The "best match " is defined as the match with the most characters before the * character; and in the event of ties, the most after. * The "literal public_urls" are especially useful when you use the SREFQUIK variant of SRE-Filter to speed up throughput. * HTACCESS file lookup is suppressed whenever the request matches a PUBLIC_URLS (HTACCESS access controls, redirection, etc. will not be attempted). * In general, all files are assumed to be relative to the data directory or a virtual directory. Note that for "literal" public_url's, virtual directories are NOT checked -- so all files are assumed to be relative to the data directory Reminder: You can skip the "data directory" lookup by explicitly naming the file that this PUBLIC_URL maps to. You can do this simply by adding the (fully qualified) file name after the LITERAL option. For example: PUBLIC_URLS.3='STORE/AD1.HTM LITERAL D:\SHOP\ADS\AD_1.HTM * If you have no PUBLIC_URLS, set PUBLIC_URLS.1=0 * To illustrate use of PUBLIC_URLS, SRE-Filter is shipped with PUBLIC_URLS (and an ALIAS_FILE) setup to respond to a PUBLIC request by listing all files in the PUBFILES/ subdirectory of the data directory (assuming you've created such a subdirectory). * If a request matches a PUBLIC_URLS, then: If PRE_FILTER=FIRST, then the pre filter will be called. Otherwise, it will NOT be called (that is, PRE_FILTER="YES" is treated as a NO). * You can specify PUBLIC_URLS on a host-specific basis. In fact, non-host specific values of PUBLIC_URLS will NOT be used as "default" values! To do this, append a .HOST_NICKNAME to PUBLIC_ULRS. For example: PUBLIC_URLS.2.ZOO='HOURS.HTM LITERAL' indicates that this entry applies to requests to the "host" with a host nickname of ZOO. CAUTION: When using "literal PUBLIC_URLS with fully qualified file names" (and other types of local redirection) URL resolution by the client's browser may have unexpected consequences. See the discussion of "local vs remote redirection" at the bottom of this document for details! ************** PUBLIC_PRIVS. Additional privileges for all clients. A space delimited list of additional privileges to be granted to all clients). Set PUBLIC_PRIVS=" " if no additional privileges are needed. Examples: public_privs=" PUBLIC MESSBOX=*" public_privs=' PUBLIC MESSBOX=FORUM1 MESSBOX=PUBGRP* ' Notes: * PUBLIC_PRIVS are used for requests to PUBLIC_URLS. * The MESSBOX=* privilege (the SRE-Filter default) grants read/write access to all "message boxes" (assuming Selector and FILE specific access controls are NOT in place). In contrast, MESSBOX=FORUM1 permits access to the FORUM1 message box. and MESSBOX=PUBGRP* allows access to PUBGRP01, PUBGRP02, etc. * The CONTROL privilege allows some of the special (the !xxx) commands. * The BROADCAST privilege allows the user to "broadcast" e-mail messages using the SRE-Filter message facility. * The VIEWMESS privilege allows a client to download a SRE-Filter message box file (as an alternative to using the FORUM facility). (PUBLIC_PRIVS can be host specific) ******* RECORD_OPTION : Select whether to record all allowed requests. Used if you want to keep a running total of requests. RECORD_OPTION can take several values NO = Do NOT Keep track of requests YES = Remove argument list, and keep track of all requests. YES_ALL = Do not remove argument list, and keep track of all requests. FILE = Record using the name of the requested file (or script) If RECORD_OPTION is <> NO, results will be written to the RECORD_ALL_FILE. Example: record_option="YES" Notes: * The "argument list" is the ? (and anything that follows it) in a request selector. * If you use YES_ALL or FILE, be prepared for your RECORD_ALL_FILE to grow quite large. * Note that RECORD_ALL_FILE can be hand-edited. You may want to add appropriate "wildcarded" entries (such as /TEMP/*) to keep track of all temporary files, thereby avoiding the creation of lots of useless entries. * The RECORD_CACHE_FILE (see section 2a) is used to control caching of the RECORD_ALL_FILE. * See the WRITE_LOGS parameters for an alternative auditing mechanism (the common-log file). (RECORD_OPTION can be host specific) ************ SMTP_GATEWAY: Domain name of an SMTP server The SMTP_GATEWAY is used when e-mail messages are to be sent; as may be attempted by MESSAGE, FORUM, and several other SRE-Filter facilties. This should be the domain name of a SMTP mail server. You can use your own server as the SMTP gateway by running SENDMAIL. Example: SMTP_GATEWAY=MAILBOX.BIG.EDU (SMTP_GATEWAY can be host specific) *********** SSI_CACHE_ON SSI_CACHE_ON is used to enable the server side include cache (SSI-cache). NO : Turn the SSI-Cache off -- HTML document will not be cached. YES : Turn the SSI-Cache on. The SSI-cache is used to store "compiled" versions of HTML documents that contain server side includes. When a request for such document arrives, SRE-Filter will return it (perhaps with further modifications). Turning off caching is sometimes useful in highly dynamic environments; say, where INCLUDE files are constantly changing. Example: SSI_CACHE_ON = 'YES' Notes: * For further discussion of SSI-caching, please see the SSICACHE.HTM file. * The SSI_CACHE_SIZE variable (set in SREFILTR.80) can also be used to disable the SSI-Cache. (SSI_CACHE_ON can be host specific) ******* SSI_SHTML_ONLY: Process server side includes for .SHT or .SHTML files only SRE-Filter can be instructed to attempt server side includes (SSIs) only on files with a .SHT or .SHTML extension -- files with .HTM (or .HTML) extension will NOT be checked for server side includes. This can speed up file transfer, but does require more care when naming html files. SSI_SHTML_ONLY : NO. All HTML documents will be checked for SSIs. Note that files with .HTM .SHT .HTML and .SHTML are assumed to be html documents (more specifically, mime type text/html documents). SSI_SHTML_ONLY : YES Only .SHTM and .SHTML files are checked for SSIs. Notes: * SSIs are NOT processed when NO_INCLUDE='NO' (or if there is no NO_SSI permission). * The list of "SSI capable" files can be modified to include files with extensions other then .SHT and .SHTML. See the description of the SSI_EXTENSIONS variable (in the next section of this document) for details. REMINDER: SRE-Filter never caches files that contain SSIs (since these are likely to change on a per request basis). (SSI_SHTML_ONLY can be host specific) **************** THE_REALM: "Realm" name to use in requests for username/password. This is the "realm" which client are "challenged" by -- most browsers will display this "realm" information when asking for username/password (as when CHECKLOG<>'ALWAYS' and a non-inhouse client comes a calling) Example: the_realm="OUR WEB SITE" Notes: * Note that the "SEL-specific realm" (specified in the access file) is used if it's available. If no "SEL-specific realm" is available, the value of THE_REALM is used. * THE_REALM can be host specific. For example: THE_REALM.ZOO='ZOO_SITE' ******* UNALLOWEDIPS : Stem variable of "disallowed" IP addresses. You can specify a set of ips that are NOT allowed in (a keep out pests option). The syntax is the same (* allowed, consecutive numbering), as the INHOUSEIPS. variables. Note: UNALLOWEDIPS. is ALWAYS checked (even if checklog=NO) -- and if a match is found, no logon is requested (they can't get in) Example: unallowedips.1 = "149.126.12.*" unallowedips.2="136.12.5.212" unallowedips.3=0 Example2: unallowedips.1="*.*.*.*" unallowedips.2=0 Only OWNERS and INHOUSEIPS.n clients can get in ! Example3 : unallowedips.1 = 0 means that no one is automatically excluded. Notes: * UNALLOWEDIPS. is checked after INHOUSEIPS. and OWNERS * We recommend that the last unallowedips. value = 0. UNALLOWEDIPS. may be specified on a host-specific basis. In fact, non-host specific values of UNALLOWEDIPS will NOT be used as "default" values (see INHOUSEIPS. for details)! ******** UPLOAD_MAXSIZE: The maximum size (in Kbytes) allowed in a uploaded file. Uploaded files are placed on the server when a GET_URL or a PUT_FILE request selector is recieved. Set this small (say, 20) if you don't want large files dumped onto your machine. Set it to 0 to disable all file uploads! Example: upload_MAXSIZE=50 Note: Uploads using the PUT http method are not limited by the UPLOAD_MAXSIZE variable. (UPLOAD_MAXSIZE can be host specific) ******** UPLOAD_MINFREE: Space that must remain after an upload. The minimum amount of free space (in Kbytes) that must exist in the upload_DIRECTORY's hard drive after uploading a file with GET_URL or PUT_FILE. Set this large (say 100000) if you want to be certain that your hard drive doesn't get filled up). Example: upload_MINFREE=25000 Note: if either upload_MINFREE or upload_MAXSIZE are violated, file upload will not occur. (UPLOAD_MINFREE can be host specific) ******* USE_STDOUT: In "INTERPRET" keyphrases, use standard output as a means of writing results to a document. If USE_STDOUT='YES', then INTERPRET keyphrases will have two means of inserting data into your document: 1) If the "INTERPRET" code block contains interpret.results='some string' 2) All QUEUE (and PUSH) statements will be inserted (after the string stored in interpret.results If USE_STDOUT='NO', then ONLY step 1 above is used (QUEUE and PUSH commands will be ignored). With USE_STDOUT='YES', INTERPRET will work similarly to the #EXEC server side include -- except SAY generated output is NOT retained (GoServe seems to trap SAY statements, and sends their output to PMPRINTF). Hence the need to use QUEUE (or PUSH) ... Example: USE_STDOUT='YES' (USE_STDOUT can be host specific) ******* VERBOSE: Controls the extent of comments written to the Pmprintf window. Set verbose=1 if you want a fair number of status messages written to the pmprintf window. Set to verbose= 0, and only error messages and certain initialization messages will be displayed. Example: verbose=0 (VERBOSE can be host specific) Note: for even more comments, set VERBOSE=2, 3 or 4. ********* WEBMASTER: A static variable. The WEBMASTER variable is used in certain error and status messages. Note: you might also want to put specify a CONTACT "REPLACEment variable" in the repstrgs_file file. Example: webmaster='<a href="mailto:bb1@farm.ag.gov"> Webmaster </a> ' WEBMASTER may be host specific (i.e.; WEBMASTER.SWEETSHOP='CANDY@SWEET.ISP.COM') ******** WRITE_LOGS: Enable the common-log, browser, and referer logs. The WRITE_LOGS variable is used to enable recording of all requests toe the common-log audit file. In addition, browser and referer information will be written to seperate log files. YES = Enable these log files NO = Do NOT record requestsion in these log files. Example: WRITE_LOGS='YES' Note: For further details on the common-log, etc. log files, see SREFLOGS.DOC. WRITE_LOGS may be host specific. ******** List of files and directory identifier variables. NOTE: If you change these, you MUST re-start GOSERVE! MESSBOX_DIR) Directory containing message boxes, MAILBOX_DIR) The in-box directory of an SMTP server. CGI_BIN_DIR) Location of CGI-BIN programs. TEMPFILE_DIR) Directory to use for creation of "temporary" files (by external procedures). In comparison to the TEMPDATA_DIR, this is meant for short-life files (typically created by a server side program) that are meant to be downloaded in response to a subsequent request. Note: The !DELSEND "special action" looks for files in TEMPFILE_DIR. UPLOAD_DIR) Default location for uploaded files. TEMPDATA_DIR) Used for various SRE-Filter temporary files, such as _HITCACH.80, _ADDPRIV.80, and the $xxx.80 temporary "response" files. In comparison to the TEMPFILE_DIR, these are files that are used by SRE-Filter, and are not intended to be directly accessible to clients. WORKDATA_DIR) Directory containing various SRE-Filter parameter files. COUNTER_FILE) "REPLACE HITS" counter file RECORD_ALL_FILE) "Record all requests" counter file SENDFILE_FILE) File used by SENDFILE procedure to keep track of requests. ACCESS_FILE) File used to control access when ALLOW_ACCESS is binding UPLOAD_LOG) Record of "uploaded files" ALIAS_FILE) File containing the aliases. VIRTUAL_FILE) File containing "virtual directory" selector aliases. REPSTGS_FILE) REPLACEment string file USERS_FILE) Username/password file INTERPRET_FILE) File containing blocks of REXX code for use by the INTERPRET keyphrase (obsolete, retained for backwards compatability). Examples: messbox_dir='e:\goserve\MESSAGE' messbox_dir='c:\mptn\etc\mail' tempfile_dir='e:\WWW\temp' upload_dir='E:\goserve\upload' cgi_bin_dir='E:\goserve\CGI_BIN' counter_file='e:\goserve\DATA\COUNTER.CNT' record_all_file='e:\goserve\data\recrdall.cnt' sendfile_file='e:\goserve\DATA\SENDFILE.CNT' access_file='e:\goserve\DATA\ALL_FILE.CTL' tempdata_dir='e:\goserve\temp' virtual_file='E:\goserve\VIRTUAL.IN' alias_file='e:\goserve\ALIASES.IN' repstrgs_file='e:\goserve\REPSTRGS.IN' user_file='e:\goserve\USERS.IN' interpret_file='e:\goserve\INTERPET.IN' Note: The various .CNT, .CTL, and .IN files that are shipped with SRE-Filter (such as ALL_FILE.CTL) contain additional documentation. Note that these various filenames are NOT host specific, but they MAY contain host specific entries! ============================= Section 2a. Parameters in SREFILTR.80 In addition to the variable contained in INITFILT.80, there are a few variables in SREFILTR.80 which the ambitious user may wish to change. Note that NONE of these parameters are host-specfic. Furthermore, in order for changes to these variables to take effect, you MUST restart GoServe (this is not strictly true for some of these parameters, but for safety sake, we recommend restarting GoServe whenever you change any of these following values). ******** ALWAYS_CHECK_PRIVS When a request selector matches a "public_URL", SRE-Filter does not require the client to have "access privileges". However, the request may be for a SRE-Filter add-on which DOES require specific privileges. Setting ALWAYS_CHECK_PRIVS=1 tells SRE-Filter to "get the client privileges, even if she asked for a public_url". A value of 0 tells SRE-Filter to NOT lookup client privileges when PUBLIC_URLs are requested. Basically, If you know that public_urls NEVER require privilege information, setting ALWAYS_CHECK_PRIVS=0 will improve performance. If you aren't sure, the safe choice is to set ALWAYS_CHECK_PRIVS=1. Example: always_check_privs=1 ******** BACKUPSERVERLIST and LOADTHRESHOLD These variables are used to control "load balancing". When load balancing is active, the server will first check the number of active clients. If this exceeds the number specified in LOADTHRESHOLD, then the client is redirected to one of the server's listed in BACKUPSERVERLIST. LOADTHRESHOLD : If LOADTHRESHOLD=0, then this "load balancing" is not attempted. Otherwise, load balancing will occur if the number of active clients is greater then the value given. BACKUPSERVERLIST: If BACKUPSERVERLIST=' ', then load balancing is not attempted. Otherwise, it should contain a list of IP addresses of alternate (backup) servers (that presumably mirror the main site). If BACKUPSERVERLIST contains more then one entry (entries should be seperated by spaces), then a partially random method is used to select which server to redirect the client to. For example: 2 entries = 2/3 of the redirections go to the first entry. 3 entries = 1/2 go to the first entry (1/4 to 2nd and 3rd) Examples: loadthreshold=0 backupserverlist=' ' loadthreshold=6 backupserverlist='www2.oursite.net' loadthreshold=3 backupserverlist='www2.oursite.net overflow.hersite.net ' Citation: The basic idea is borrowed from Don Meyer's HTTP filter. ********** CERN_ISMAP The value(s) in the spaced delimited CERN_ISMAP variables are used to indicate that this "is an image-map request". You can specify several different values (though you should only use one of them in your "image map" URL). When one of these identifier-strings appear in a request selector, SRE-Filter assumes that the request "is a response from a mappable image" For example, if CERN_ISMAP='/MAPCERN', then selectors (that are generated by clicking on a mappable image) of the form: /MAPCERN/GIFSDIR/USMAP.MAP?123,312 will be interpreted as ... pixel 123,312, in combination with the instructions contained in /GISDIR/USMAP.MAP, is used to determine which URL to redirect the client to (where USMAP.MAP is a CERN style MAP file) IMPORTANT NOTE: the MAPCERN/ is NOT considered to be part of the directory name -- it is treated as a flag! Example: CERN_ISMAP="MAPCERN/ CGI-BIG/HTIMAGE/" Notes * The trailing / in the above example(s) is optional. * The "map file location" is interpreted using the regular sre-filter rules (relative to the GoServe data directory, or to a virtual directory) * For NCSA style image maps, see the NCSA_ISMAP variable. * CERN_ISMAP and NCSA_ISMAP replace the ISMAP_URL variable (found in pre 1.2i.325 versions of SRE-Filter). ******** DELAY_SECONDS Delay_seconds controls how frequently SRE-Filter checks input files for updates. Larger values mean more time between checks. If you never change initialization parameters, etc. you can set this to a high value (say, 1000) to reduce the load on the server. Example: delay_seconds=9 ********** DIR_CACHE_DURATION DIR_CACHE_DURATION is used by SRE-Filter's !DIR facility. It is the lifespan (in days, or fractional days) of entries in the "directory listing cache". Example: DIR_CACHE_DURATION=3 ********** DIR_CACHE_SIZE DIR_CACHE_DURATION is used by SRE-Filter's !DIR facility. It is the maximum size (in Kbytes), of the "directory listing cache". Example: DIR_CACHE_SIZE=1000 Notes: * setting DIR_CACHE_SIZE=0 will suppress use of the directory listing cache. * directory listing "cache files" are stored in the TEMPDATA_DIR, with names of _nnnnn.DSH (i.e.; _0000012.DSH). There is also a _DIRLIST.IDX file used as an index to these listings). ********** HIT_SUPERUSER_SUPPRESS If HIT_OWNER_SUPPRESS is enabled (see description above), then "OWNERS" will not have their hits recorded (in the RECORD_ALL_FILE and in the hit counter file). You can extend the "range" of HIT_SUPERUSER_SUPPRESS to include SUPERUSERs by setting HIT_SUPERUSER_SUPPRESS=1. That is, if HIT_OWNER_SUPPRESS=1 and HIT_SUPERUSER_SUPPRESS=1, the request from OWNERS and from SUPERUSERs will NOT be recorded. Otherwise (if HIT_SUPERUSER_SUPPRESS=0), SUPERUSER requests will be recorded. Example: HIT_SUPERUSER_SUPPRESS=1 (the default is 0) Note: if HIT_OWNER_SUPPRESS=0, then HIT_SUPERUSER_SUPPRESS is ignored (that is, SUPERUSER requests will be recorded). ********** NCSA_ISMAP The value(s) in the spaced delimited NCSA_ISMAP variables are used to indicate that this "is an image-map request". You can specify several different values (though you should only use one of them in your "image map" URL). When one of these identifier-strings appear in a request selector, SRE-Filter assumes that the request "is a response from a mappable image" For example, if NCSA_ISMAP='/MAPIMAGE', then selectors (that are generated by clicking on a mappable image) of the form: /MAPIMAGE/GIFSDIR/USMAP.MAP?123,312 will be interpreted as ... pixel 123,312, in combination with the instructions contained in /GISDIR/USMAP.MAP, is used to determine which URL to redirect the client to (where USMAP.MAP is an NCSA style MAP file) IMPORTANT NOTE: the MAPIMAGE/ is NOT considered to be part of the directory name -- it is treated as a flag! Example: NCSA_ISMAP="MAPIMAGE/ CGI-BIG/MAPIMAGE" Notes * The trailing / in the above example(s) is optional. * The "map file location" is interpreted using the regular sre-filter rules (relative to the GoServe data directory, or to a virtual directory) * For CERN style image maps, see the CERN_ISMAP variable. * CERN_ISMAP and NCSA_ISMAP replace the ISMAP_URL variable (found in pre 1.2i.325 versions of SRE-Filter). ********* KEY_PREFACE If the REPLACE, INCLUDE, OPTIONS, INTERPRET and SELECT "keywords" appear at the beginning of real comments (and you are using the default "server side keyphrase" delimiters of ), you might want to add a "preface" to these keywords. For example, you can add the ! character, so that SRE-Filter will look for !REPLACE, !INCLUDE, etc. Note that KEY_PREFACE=0 or KEY_PREFACE='' means "do not add a preface". Also note that the # can not be used as a preface (since it is used by the HTTPD-style #INCLUDE keyphrase). Examples: KEY_PREFACE='!' KEY_PREFACE=0 ******** LOGON_LIMIT As a security measure, SRE-Filter's "authorization facility" can limit the number of unsuccessful attempts, per IP address per minute. When this limit is exceeded, for the next minute further attempts (from this IP address will be immediately denied. To enable this, set LOGON_LIMIT to the number of logon attempts per minute. A value of 0 means "no limits". Examples: LOGON_LIMIT=0 LOGON_LIMIT=3 Warning: do NOT use LOGON_LIMIT=1 (it causes odd problems) Note: the authorization facility handles all client answers to "401 Unauthorized" server responses. These include "logon" requests and "SEL-specific" access requests. ******** MESSAGE_SCRAMBLE MESSAGE_SCRAMBLE is used to "encrypt" message-box passwords. You can change it for a wee bit extra security (though security is never going to be great). Example: message_scramble=12415 ( message_scramble should be an integer less than 1 million and greater then 0). WARNING: If you change this, existing "message" passwords will not be decodable! That is, they won't work anymore. Note: only the password, which is just used to control deletion rights, is encrypted. *********** NO_NO_RECORD The NO_NO_RECORD option can be used to suppress the !NORECORD directive. One reason to suppress !NORECORD is to prevent tricky clients from sneaking by your audit mechanisms. To disable the !NORECORD directive, set NO_NO_RECORD=1 To enable it, set NO_NO_RECORD=0 *********** RECORD_CACHE_LINES: This controls the size of the "request recorder" cache. Shrinking the size of this cache (say, if you don't have many documents) will free up memory. Increasing it (say, you have a large site, and a lot of RAM) will speed up request recording. In addition, since the RECORD_ALL_FILE is backed up and then reset when the cache grows beyond RECORD_CACHE_LINES, a larger cache may reduce fragmentation of these RECORD_ALL_FILE audit files. To suppress caching, set RECORD_CACHE_LINES=0 Example: RECORD_CACHE_LINES=750 *********** SAVE_STATE: SRE-Filter can save some "request specific" state-information: such as the "selector", the client's address, and the request headers. This information will be written to a temporary file. It is then relatively easy to access this information by using SRE-Filter's SREF_READ_STATE macrospace procedure. The most important use of this is by post-filter routines -- oftentimes a necessity, given that GoServe will CRASH if EXTRACT (and other GoServe) functions are called from a post-filter procedure. Notes: * The SREF_READ_STATE SRE-Filter macrospace procedure is designed to use the output generated by SAVE_STATE. SREF_READ_STATE can be called from an external procedure, or by a post-filter procedure, using the following syntax: info=sref_read_state(state_var,occurence,thread,thread_cache_file) where state_var can be one of: SEL REQUEST SOURCE THREAD DATE_TIME SERVER_NAME PRIVSET CLIENT CLIENT_NAME CLIENT_PORT SERVER SERVER_PORT TRANSACTION or state_var can be one of the "request header" variables. * For more details, see the description of SREF_READ_STATE in SREFPRC1.DOC (SREFPRC1.DOC is available from: http://rpbcam.econ.ag.gov/srefilter/srefprc1.doc). ************ SEM_MAXWAIT The "independent threads" that help SRE-Filter work by waiting on queues. The waiting is partially contolled by a semaphores, which are set whenever anything is written to a queue. Since OS/2 can be a mite slow about writing semaphores, it is sometimes convenient to check the queue, and then go back to waiting if nothing is there. To increase the frequency that this "check queue even though the semaphore hasn't been set" occurs, select a low value of SEM_MAXWAIT. Note that SEM_MAXWAIT is in milliseconds, so values under 100 are considered low. A possible drawback is that the smaller SEM_MAXWAIT is, the more SRE-Filter will engage in useless queue examinations. The best value to use should be determined by experimentation. Example: SEM_MAXWAIT=15000 ********* SSI_EXTENSIONS: File extensions that are equivalent to SHTML. The SSI_EXTENSIONS variable contains a space delimited list of file extensions that will be treated as "SHTML" files. That is, when SSI_SHTML_ONLY='YES', only files with one of with these extensions will have server side includes added. If you add to this list, you may also need to specify that the file has a text/html MIME type. To do this, you should add entries to the MEDIATYP.RXX file located in the GoServe directory. Note: SRE-Filter's default value of ssi_extensions is: ssi_extensions=' SHT SHTML HTML-SSI HTM-SSI ' **************** SSI_CACHE_SIZE SSI_CACHE_SIZE is used to set the size of the "server side include cache". You should enter the size in Kilobytes. For example: SSI_CACHE_SIZE=5000 (the default) corresponds to a cache size of 5M. Notes: * For further discussion of SSI-caching, please see the SSICACHE.HTM file. * Cached files are stored in your TEMPDATA_DIR directory (typically, GOSERVE\TEMP). They have names of _CSH????.80 (or .nnn, if you are using port .nnn). * Once the size of the cached files exceeds this amount, the oldest entries will be deleted (where oldest is measured in terms of "last request"). * Setting SSI_CACHE_SIZE=0 will turn the SSI-Cache off (regardless of the value of SSI_CACHE_ON). **************** SSI_CACHE_DURATION SSI_CACHE_DURATION is used to set (in days) the "lifespan" of entries in the server side include cache. After this lifespan has been exceeded, the entry will die. This helps ensure that documents do not get "too far" out of date (thus, egregious out-of-sync errors won't last forever). Examples: SSI_CACHE_DURATION=0.5 -- a 12 hr. lifespan. SSI_CACHE_DURATION=30 -- a 30 day lifespan SSI_CACHE_DURATION=0 -- infinite lifespan Note: You can use the  SSI keyphrase to override this "default" value on a file-by-file basis. **************** SSI_CACHE_STAMP The SSI_CACHE_STAMP dictates which fields to use when determining whether a SSI-cache "trigger" file has changed. SSI_CACHE_DURATION can have one of the following values: ALL -- Use time,date, and size (if any change, the trigger is considered to be out-of-sync) DATE -- Just use the date TIME -- Just use the time (hr/minute) DATETIME -- Use the time and date SIZE -- Just use the size Note: You can use the  SSI keyphrase, where stamp is one of the above values, to override this "default" value on a file-by-file basis. ======================================== Section 3. A Comparison of Local vs. Remote Redirection of URL's One of the strengths of SRE-Filter is the variety of redirection mechanisms it offers, where redirection implies "sending the client a file that is not a direct mapping of the request selector". Redirection has two general classes: remote and local. "Remote" redirection, which is what most of the literature simply calls redirection, involves telling the client's browser that "the url you have requested has been moved to xxxx", where xxxx may be any URL -- it need not be on the same server, and it need not have the same name. For example, an alias (in the alias-file) of whatgot http://www.mine.org/dir1/index1.htm would cause the server to send back a "302" response to the client's browser whenever a request for "whatgot" arrives. This 302 response, would instruct the client's browser to automatically request http://www.mine.org/dir1/index1.htm. "Local" redirection is handled solely by the server, and involves substituting the "request selector" with another "request selector". SRE-Filter has a number of methods of specifying "local redirection", such as the DEFAULT, AUTO_NAME, NOEXT_TYPE variables, and the use of aliases of the form: whatgot dir1/index.htm. In all these cases, the browser assumes that the document it recieves is a direct result of the original request selector issued. While offering a real convenience, with less demands on the client, local redirection can have undesired effects. In particular, "partial URLS" in documents that were sent as the result of a local alias may not work properly. A short discussion of how browsers handle partial URLs is germane: When a link that is specified as a "partial URL" (such as <img src="wow.gif"> or <a href="wow.htm">) appears in one of the html documents on your site,the URL actually requested by the browser is determined by using the "full" URL that invoked this html document (that contains this partial URL). For example, if the client asks for, and recieves: http://www.mine.net/dir1/index.htm, and index.htm contains a "partial URL" of: <img src="wow.gif">, the client's browser would then try to get: http://www.mine.net/dir1/wow.gif. In other words, when the browser is asked to get a partial url (that does NOT begin with a /), it will take everything before the last / in the "parent" URL (of the document that contains this partial URL) and then append the requested partial URL. (Actually, if a URL does not begin with http://, it will append the "begins with / partial URL" to the http://.../ component of the "full URL".) The use of the "local redirection" features of SRE-Filter is complicated by this "automatic resolution of partial URLS". For example, if the client requests: http://www.mine.net/dir1 and SRE-Filter's auto-naming feature converts requested URL's (abstracting from the http://www.mine.net/ component) of dir1 to /dir1/index.htm, and then sends /dir1/index.htm ... the browser has no way of knowing this -- that is, the client's browser will assume the server sent a file named : dir1 that was located in the "root of www.mine.net". So, the browser would assume that a link (in this document) to wow.gif is also located in the root (of www.mine.net), and would request http://www.mine.net/wow.gif (which is wrong, it should request http://www.mine.net/dir/wow.gif) So, if you want to use local redirection (AUTO_NAME, aliases, etc.) you should: 1) fully specify the links in your documents .. i.e.; use /dir1/foo.gif instead of foo.gif 2) Use a <base> element in the <HEAD> of each document... i.e.; <base href="/dir1/"> 3) Tell people to end "non file requests" with a "/" ... i.e.; tell people to use "dir1/" rather then "dir1" 4) Don't use local redirection (just use remote redirection). This entails the use of "remote" aliases instead of AUTO_NAME, DEFAULT, and NOEXT_TYPE. 5) Set NOEXT_TYPE='REDIR' None of these are great solutions. We might add a "automatically add the appropriate <base> element to the <HEAD> of all HTML documents" feature to SRE-Filter in the future??? ....But, since many browsers don't seem to understand the <BASE> element (WEB ex 1.11d does, but I'm not sure about others)... ======================================== Section 3a. An example of local redirection. Local redirection, despite it's potential pitfalls, does provide some fairly powerful configuration possibilitles. As an example, consider recording "successful" transfers of one of several files: STUFF.ZIP and OTHRSTUF.ZIP. i) The simple method. Assume an HTML document with the following links <A href="stuff.zip">Get our stuff </a> or, <A href="othrstuf.zip">get our other stuff </a> Also assume that RECORD_OPTION='YES' When a client invokes one of these links, SRE-Filter will augment the appropriate entry in the RECORD_ALL_FILE. If you wish to record "each individual" request, you could wade through SRE-Filter's "common-log" audit file. A better idea is to use SENDFILE with the COUNTER option: ii) Using SENDFILE, the above would be: <A href="sendfile?stuff.zip&counter=file=stuff">Get our stuff </a> or, <A href="sendfile?othrstuf.zip&counter=file=othrstuf"> get our other stuff </a> The SENDFILE facility is used to transfer the document; and upon successful transfer, the appropriate .CNT file is updated. One nice feature of SENDFILE is that unsuccessful (or aborted) transfers are explicitily noted. There is a minor problem: many browsers (i.e.; Netscape) will give the client a default filename of "SENDFILE". This will probably confuse a number of folks. Fortunately, it's not hard to avoid this problem by using local redirection. iii) Using local redirection, we use what looks like a standard URL, with the following in the HTML document: <A href="stuff.zip">Get our stuff </a> <A href="othrstuf.zip"> or, get our other stuff </a> In addition, we include the following entries in the ALIAS_FILE: stuff.zip sendfile?stuff.zip&counter=file=stuff othrstuf.zip sendfile?othrstuf.zip&counter=file=othrstuf When a request for "stuff.zip" arrives, SRE-Filter uses the sendfile?stuff.zip&counter=file=stuff alias. The client's browser doesn't know this, and will assume the file's name is stuff.zip (which is the desired assumption). This use of aliases could not be replicated with virtual directories, or with remote redirection! ======================================== Section 4. A Simple Example of using PUBLIC_URLS to set up a site This section discusses how one might efficiently design a web site with three levels of security: 1)Open, unmonitored access 2)Open, monitored access 3)Controlled access. When using SRE-Filter, the best strategy for increasing throughput is to make extensive use of PUBLIC_URLS, and to use the SREFQUIK version of SRE-Filter. More precisely, one should liberally specify "literal" PUBLIC_URLS. With this in mind, consider the following PUBLIC_URLS: PUBLIC_URLS.1='~/* LITERAL_NORECORD' PUBLIC_URLS.2='~/*.SHTML NORECORD ' (or, ~/*.SHT if you are using FAT) PUBLIC_URLS.3='PUBLIC/*.HTM LITERAL' PUBLIC_URLS.4='PUBLIC/*.SHTML' PUBLIC_URLS.5='PUBLIC/*.GIF LITERAL_NORECORD' PUBLIC_URLS.6='HELLO LITERAL D:\WWW\INDEX.HTM' PUBLIC_URLS.7='STAFF/* LITERAL D:\WWW\PEOPLE\STAFF\*' PUBLIC_URLS.8-'STAFF/*.SHTML ' public_urls.9=0 the following parameter settings: SSI_SHTML_ONLY='YES' HOME_DIR='STUDENTS/PERSONAL' and the following entry in the ALIAS_FILE: STAFF/*.SHTML PEOPLE/STAFF/*.SHTML PUBLIC_URLS.1 and .2 deal with documents available to the "open, unmonitored" class of requests (i.e.; requests to student owned subdirectories under the STUDENTS/PERSONAL directory of the data directory). The LITERAL_NORECORD in .1 instructs SRE-Filter to map the request selector directly to the ~ sub-directory, and to suppress SRE-Filter auditing. The NORECORD in .2 only suppresses SRE-Filter auditing -- since LITERAL supresses server side includes, we do not want to use LITERAL_NORECORD to suppress audit file update. The third and fourth entries, which deal with the "open, monitored access" class of requests, are equivalent to the first two -- except SRE-Filter auditing is not suppressed. The fifth entry suppresses auditing for .GIF files located in the PUBLIC subdirectory, which we may assume are relatively unimportant to keep track of. The sixth entry is equivalent to an "alias", with easy to remember request selector mapped to a specific file. The seventh and eighth entries are similar to the fourth and fifth. URLs that begin with "STAFF/" (but that do not end in .SHTML) will refer to files in or under D:\WWW\PEOPLE\STAFF. In contrast, selectors that begin with STAFF, and end with .SHTML, are interpreted using the usual SRE-Filter rules (i.e.; in the data directory or a virtual directory). Also note that all requests to STAFF/* will be recorded (including .GIF files). Lastly, requests that do NOT match these PUBLIC_URLS will be passed through to SREFILTR.80, and will be subject to the whatever access controls (and aliasing) have been specified. In other words, the "controlled access" requests are the default! Note: "suppression of SRE-Filter auditing" does NOT suppress additions to GoServe's GOAUDIT.80 file. It does suppress changes to SRE-Filter's RECORD_ALL_FILE --- End of Document.